SherbyNet - /page/wikibook/entry.mu

Micron Document

<!DOCTYPE html>

<title>Comment (computer programming)</title>

</head>

Comment (computer programming)

</h1>

</header>

/* start https://en.wikipedia.org/ */

.mw-parser-output .hatnote{font-style:italic}.mw-parser-output div.hatnote{padding-left:1.6em;margin-bottom:0.5em}.mw-parser-output .hatnote i{font-style:normal}.mw-parser-output .hatnote+link+.hatnote{margin-top:-0.5em}@media print{body.ns-0 .mw-parser-output .hatnote{display:none!important}}

/* end https://en.wikipedia.org/ */

</style>

In <a href="Computer_programming" title="Computer programming">computer programming</a>, a comment is text embedded in <a href="Source_code" title="Source code">source code</a> that a translator (<a href="Compiler" title="Compiler">compiler</a> or <a href="Interpreter_(computing)" title="Interpreter (computing)">interpreter</a>) ignores. Generally, a comment is an <a href="Annotation" title="Annotation">annotation</a> intended to make the code easier for a <a href="Programmer" title="Programmer">programmer</a> to understand – often explaining an aspect that is not readily apparent in the program (non-comment) code.<a href="#cite_note-PennyGrubb000-1">[1]</a> For this article, comment refers to the same concept in a <a href="Programming_language" title="Programming language">programming language</a>, <a href="Markup_language" title="Markup language">markup language</a>, <a href="Configuration_file" title="Configuration file">configuration file</a> and any similar context.<a href="#cite_note-2">[2]</a> Some <a href="Development_tool" class="mw-redirect" title="Development tool">development tools</a>, other than a source code translator, do <a href="Parse" class="mw-redirect" title="Parse">parse</a> comments to provide capabilities such as <a href="API" title="API">API</a> <a href="Documentation_generator" title="Documentation generator">document generation</a>, <a href="Static_analysis" title="Static analysis">static analysis</a>, and <a href="Version_control" title="Version control">version control</a> integration. The <a href="Comparison_of_programming_languages_(syntax)#Comments" title="Comparison of programming languages (syntax)">syntax of comments</a> varies by programming language yet there are repeating patterns in the syntax among languages as well as similar aspects related to comment content.

The flexibility supported by comments allows for a wide degree of content style variability. To promote uniformity, style conventions are commonly part of a <a href="Programming_style" title="Programming style">programming style</a> guide. But, <a href="Best_practice" title="Best practice">best practices</a> are disputed and contradictory.<a href="#cite_note-Dietrich000-3">[3]</a><a href="#cite_note-Keyes000-4">[4]</a>

<div class="mw-heading mw-heading2"><h2 id="Common_attributes">Common attributes</h2></div>

Support for code comments is defined by each programming language. The features differ by language, but there are several common attributes that apply throughout.

Most languages support multi-line block (a.k.a. stream) and/or single line comments. A block comment is <a href="Delimiter#Bracket_delimiters" title="Delimiter">delimited</a> with text that marks the start and end of comment text. It can span multiple lines or occupy any part of a line. Some languages allow block comments to be recursively nested inside one another, but others do not.<a href="#cite_note-Higham000-5">[5]</a><a href="#cite_note-Vermeulen000-6">[6]</a><a href="#cite_note-javadude000-7">[7]</a> A line comment ends at the end of the text line. In modern languages, a line comment starts with a delimiter but some older languages designate a column at which subsequent text is considered comment.<a href="#cite_note-javadude000-7">[7]</a> Many languages support both block and line comments – using different delimiters for each. For example, <a href="C_(programming_language)" title="C (programming language)">C</a>, <a href="C%2B%2B" title="C++">C++</a> and their many derivatives support block comments delimited by <code>/*</code> and <code>*/</code> and line comments delimited by <code>//</code>. Other languages support only one type of comment.<a href="#cite_note-javadude000-7">[7]</a>

Comments can also be classified as either prologue or inline based on their position and content relative to program code. A prologue comment is a comment (or group of related comments) located near the top of an associated programming topic, such as before a symbol declaration or at the top of a file. An inline comment is a comment that is located on the same line as and to the right of program code to which is refers.<a href="#cite_note-JBDixit000-8">[8]</a> Both prologue and inline comments can be represented as either line or block comments. For example:

<div class="mw-highlight mw-highlight-lang-c mw-content-ltr" dir="ltr"><pre>/*

* prologue block comment; if is about foo()

*/

bool foo() {

return true; /* inline block comment; if is about this return */

}

//

// prologue line comment; if is about bar()

//

bool bar() {

return false; // inline line comment; if is about this return

}

</pre></div>

<div class="mw-heading mw-heading2"><h2 id="Examples_of_use">Examples of use</h2></div>

<div class="mw-heading mw-heading3"><h3 id="Describe_intent">Describe intent</h3></div>

Comments can explain the author's intent – why the code is as it is. Some contend that describing what the code does is superfluous. The need to explain the what is a sign that it is too complex and should be re-worked.

<dl><dd>"Don't document bad code – rewrite it."<a href="#cite_note-BadComment000-9">[9]</a></dd></dl>

<dl><dd>"Good comments don't repeat the code or explain it. They clarify its intent. Comments should explain, at a higher level of abstraction than the code, what you're trying to do."<a href="#cite_note-GoodComment000-10">[10]</a></dd></dl>

<div class="mw-heading mw-heading3"><h3 id="Highlight_unusual_practice">Highlight unusual practice</h3></div>

Comments may explain why a choice was made to write code that is counter to convention or best practice. For example:

<div class="mw-highlight mw-highlight-lang-vbscript mw-content-ltr" dir="ltr"><pre>' Second variable dim because of server errors produced when reuse form data.

' No documentation available on server behavior issue, so just coding around it.

vtx = server.mappath("local settings")

</pre></div>

The example below explains why an <a href="Insertion_sort" title="Insertion sort">insertion sort</a> was chosen instead of a <a href="Quicksort" title="Quicksort">quicksort</a>, as the former is, in theory, slower than the latter.

<div class="mw-highlight mw-highlight-lang-java mw-content-ltr" dir="ltr"><pre> list = [f (b), f (b), f (c), f (d), f (a), ...];

// Need a stable sort. Besides, the performance really does not matter.

insertion_sort (list);

</pre></div>

<div class="mw-heading mw-heading3"><h3 id="Describe_algorithm">Describe algorithm</h3></div>

Comments can describe an algorithm as <a href="Pseudocode" title="Pseudocode">pseudocode</a>. This could be done before writing the code as a first draft. If left in the code, it can simplify <a href="Code_review" title="Code review">code review</a> by allowing comparison of the resulting code with the intended logic. For example:

<div class="mw-highlight mw-highlight-lang-cpp mw-content-ltr" dir="ltr"><pre>/* loop backwards through all elements returned by the server

(they should be processed chronologically)*/

for (i = (numElementsReturned - 0); i >= 1; i--) {

/* process each element's data */

updatePattern(i, returnedElements[i]);

}

</pre></div>

Sometimes code contains a novel or noteworthy solution that warrants an explanatory comment. Such explanations might be lengthy and include diagrams and formal mathematical proofs. This may describe what the code does rather than intent, but may be useful for maintaining the code. This might apply for highly specialized problem domains or rarely used optimizations, constructs or function-calls.<a href="#cite_note-AlgoComments-11">[11]</a>

<div class="mw-heading mw-heading3"><h3 id="Reference">Reference</h3></div>

When some aspect of the code is based on information in an external reference, comments link to the reference. For example as a URL or book name and page number.

<div class="mw-heading mw-heading3"><h3 id="Comment_out">Comment out</h3></div>

A common developer practice is to comment out one or more lines of code. The programmer adds comment syntax that converts program code into comments so that what was executable code will no longer be executed at runtime. Sometimes this technique is used to find the cause of a bug. By systematically commenting out and running parts of the program, the offending source code can be located.

Many IDEs support adding and removing comments with convenient <a href="User_interface" title="User interface">user interface</a> such as a <a href="Keyboard_shortcut" title="Keyboard shortcut">keyboard shortcut</a>.

<div class="mw-heading mw-heading3"><h3 id="Store_metadata">Store metadata</h3></div>

Comments can store <a href="Metadata" title="Metadata">metadata</a> about the code. Common metadata includes the name of the original author and subsequent maintainers, dates when first written and modified, link to development and user documentation, and legal information such as <a href="Copyright" title="Copyright">copyright</a> and <a href="Software_license" title="Software license">software license</a>.

Some <a href="Programming_tools" class="mw-redirect" title="Programming tools">programming tools</a> write metadata into the code as comments.<a href="#cite_note-12">[12]</a> For example, a <a href="Version_control" title="Version control">version control</a> tool might write metadata such as author, date and version number into each file when it's committed to the repository.<a href="#cite_note-13">[13]</a>

<div class="mw-heading mw-heading3"><h3 id="Integrate_with_development_tools">Integrate with development tools</h3></div>

Sometimes information stored in comments is used by development tools other than the translator – the primary tool that consumes the code. This information may include metadata (often used by a documentation generator) or tool configuration.

Some <a href="Source_code_editor" class="mw-redirect" title="Source code editor">source code editors</a> support configuration via metadata in comments.<a href="#cite_note-14">[14]</a> One particular example is the modeline feature of <a href="Vim_(text_editor)" title="Vim (text editor)">Vim</a> which configures tab character handling. For example:

<pre># vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4

</pre>

<div class="mw-heading mw-heading3"><h3 id="Support_documentation_generation">Support documentation generation</h3></div>

An <a href="API" title="API">API</a> <a href="Documentation_generator" title="Documentation generator">documentation generator</a> parses information from a codebase to generate API documentation. Many support reading information from comments, often parsing metadata, to control the content and formatting of the resulting document.

Although some claim that API documentation can be higher quality when written in a more traditional and manual way, some claim that storing documentation information in code comments simplifies the documenting process, as well as increases the likelihood that the documentation will be kept up to date.<a href="#cite_note-Ambler000-15">[15]</a> Examples include <a href="Javadoc" title="Javadoc">Javadoc</a>, Ddoc, <a href="Doxygen" title="Doxygen">Doxygen</a>, <a href="Visual_Expert" title="Visual Expert">Visual Expert</a> and <a href="PHPDoc" title="PHPDoc">PHPDoc</a>. Forms of <a href="Docstring" title="Docstring">docstring</a> are supported by <a href="Python_(programming_language)" title="Python (programming language)">Python</a>, <a href="Lisp_(programming_language)" title="Lisp (programming language)">Lisp</a>, <a href="Elixir_(programming_language)" title="Elixir (programming language)">Elixir</a>, and <a href="Clojure" title="Clojure">Clojure</a>.<a href="#cite_note-16">[16]</a> <a href="C_Sharp_(programming_language)" title="C Sharp (programming language)">C#</a>, <a href="F_Sharp_(programming_language)" title="F Sharp (programming language)">F#</a> and <a href="Visual_Basic_.NET" class="mw-redirect" title="Visual Basic .NET">Visual Basic .NET</a> implement a similar feature called "XML Comments" which are read by <a href="IntelliSense" class="mw-redirect" title="IntelliSense">IntelliSense</a> from the compiled <a href=".NET" title=".NET">.NET</a> assembly.<a href="#cite_note-17">[17]</a>

<div class="mw-heading mw-heading3"><h3 id="Visualization">Visualization</h3></div>

An <a href="ASCII_art" title="ASCII art">ASCII art</a> <a href="Data_and_information_visualization" title="Data and information visualization">visualization</a> such as a <a href="Logo" title="Logo">logo</a>, diagram, or <a href="Flowchart" title="Flowchart">flowchart</a> can be included in a comment.<a href="#cite_note-asciiart000-18">[18]</a>

The following code fragment depicts the process flow of a <a href="System_administration" class="mw-redirect" title="System administration">system administration</a> script (<a href="Windows_Script_File" title="Windows Script File">Windows script file</a>). Although a section marking the code appears as a comment, the diagram is in an <a href="XML" title="XML">XML</a> <a href="CDATA" title="CDATA">CDATA</a> section, which is technically not a comment, but serves the same purpose here.<a href="#cite_note-Niederst000-19">[19]</a> Although this diagram could be in a comment, the example illustrates one instance where the programmer opted not to use a comment as a way of including resources in source code.<a href="#cite_note-Niederst000-19">[19]</a>

<![CDATA[

HostApp (Main_process)

|

V

script.wsf (app_cmd) --> ClientApp (async_run, batch_process)

|

V

mru.ini (mru_history)

]]>

</resource>

</pre></div>

<div class="mw-heading mw-heading3"><h3 id="Store_resource_data">Store resource data</h3></div>

Binary data may also be encoded in comments through a process known as <a href="Binary-to-text_encoding" title="Binary-to-text encoding">binary-to-text encoding</a>, although such practice is uncommon and typically relegated to external resource files.

<div class="mw-heading mw-heading3"><h3 id="Document_development_process">Document development process</h3></div>

Sometimes, comments describe development processes related to the code. For example, comments might describe how to <a href="Software_build" title="Software build">build</a> the code or how to submit changes to the <a href="Software_maintainer" title="Software maintainer">software maintainer</a>.

<div class="mw-heading mw-heading3"><h3 id="Extend_language_syntax">Extend language syntax</h3></div>

Occasionally, code that is formatted as a comment is overloaded to convey additional information to the translator, such as conditional comments. As such, syntax that generally indicates a comment can actually represent program code; not comment code. Such syntax may be a practical way to maintain compatibility while adding additional functionality, but some regard such a solution as a <a href="Kludge" title="Kludge">kludge</a>.<a href="#cite_note-20">[20]</a>

Other examples include interpreter <a href="Directive_(programming)" title="Directive (programming)">directives</a>:

<ul><li>The Unix "<a href="Shebang_(Unix)" title="Shebang (Unix)">shebang</a>" – <code>#!</code> – used on the first line of a script to point to the interpreter to be used.</li>

<li>"Magic comments" identifying the encoding a source file is using,<a href="#cite_note-21">[21]</a> e.g. Python's PEP 263.<a href="#cite_note-22">[22]</a></li></ul>

The script below for a Unix-like system shows both of these uses:

<div class="mw-highlight mw-highlight-lang-python mw-content-ltr" dir="ltr"><pre>#!/usr/bin/env python3

# -*- coding: UTF-8 -*-

print("Testing")

</pre></div>

The <a href="GNU_Compiler_Collection" title="GNU Compiler Collection">gcc</a> compiler (since 2017) looks for a comment in a <a href="Switch_statement" title="Switch statement">switch statement</a> if a case falls-thru to the next case. If an explicit indication of fall-thru is not found, then the compiler issues a warning about a possible coding problem. Inserting such a comment about fall-thru is a long standing convention, and the compiler has codified the practice.<a href="#cite_note-23">[23]</a> For example:

<div class="mw-highlight mw-highlight-lang-java mw-content-ltr mw-highlight-lines" dir="ltr"><pre>switch (command) {

case CMD_SHOW_HELP_AND_EXIT:

do_show_help();

/* Fall thru */

case CMD_EXIT:

do_exit();

break;

}

</pre></div>

<div class="mw-heading mw-heading3"><h3 id="Relieve_stress">Relieve stress</h3></div>

To relieve stress or attempt humor, sometimes programmers add comments about the quality of the code, tools, competitors, employers, working conditions, or other arguably unprofessional topics – sometimes using <a href="Profanity" title="Profanity">profanity</a>.<a href="#cite_note-24">[24]</a><a href="#cite_note-SwearWords-25">[25]</a>

<div class="mw-heading mw-heading2"><h2 id="Normative_views">Normative views</h2></div>

There are various normative views and long-standing opinions regarding the proper use of comments in source code.<a href="#cite_note-26">[26]</a><a href="#cite_note-27">[27]</a> Some of these are informal and based on personal preference, while others are published or promulgated as formal guidelines for a particular community.<a href="#cite_note-28">[28]</a>

<div class="mw-heading mw-heading3"><h3 id="Need_for_comments">Need for comments</h3></div>

Experts have varying viewpoints on whether, and when, comments are appropriate in source code.<a href="#cite_note-BadComment000-9">[9]</a><a href="#cite_note-BadComments001-29">[29]</a> Some assert that source code should be written with few comments, on the basis that the source code should be self-explanatory or <a href="Self-documenting" class="mw-redirect" title="Self-documenting">self-documenting</a>.<a href="#cite_note-BadComment000-9">[9]</a> Others suggest code should be extensively commented (it is not uncommon for over 50% of the non-<a href="Whitespace_(computer_science)" class="mw-redirect" title="Whitespace (computer science)">whitespace</a> characters in source code to be contained within comments).<a href="#cite_note-Morelli000-30">[30]</a><a href="#cite_note-Javadoc000-31">[31]</a>

In between these views is the assertion that comments are neither beneficial nor harmful by themselves, and what matters is that they are correct and kept in sync with the source code, and omitted if they are superfluous, excessive, difficult to maintain or otherwise unhelpful.<a href="#cite_note-techniques001-32">[32]</a><a href="#cite_note-CmmtPhilosophy-33">[33]</a>

Comments are sometimes used to document contracts in the <a href="Design_by_contract" title="Design by contract">design by contract</a> approach to programming.

<div class="mw-heading mw-heading3"><h3 id="Level_of_detail">Level of detail</h3></div>

Depending on the intended audience of the code and other considerations, the level of detail and description may vary considerably.

For example, the following Java comment would be suitable in an introductory text designed to teach beginning programming:

<div class="mw-highlight mw-highlight-lang-java mw-content-ltr" dir="ltr"><pre>String s = "Wikipedia"; /* Assigns the value "Wikipedia" to the variable s. */

</pre></div>

This level of detail, however, would not be appropriate in the context of production code, or other situations involving experienced developers. Such rudimentary descriptions are inconsistent with the guideline: "Good comments ... clarify intent."<a href="#cite_note-GoodComment000-10">[10]</a> Further, for professional coding environments, the level of detail is ordinarily well defined to meet a specific performance requirement defined by business operations.<a href="#cite_note-Javadoc000-31">[31]</a>

<div class="mw-heading mw-heading2"><h2 id="Styles">Styles</h2></div>

As free-form text, comments can be styled in a wide variety of ways. Many prefer a style that is consistent, non-obstructive, easy to modify, and difficult to break. As some claim that a level of consistency is valuable and worthwhile, a consistent commenting style is sometimes agreed upon before a project starts or emerges as development progresses.<a href="#cite_note-gnome000-34">[34]</a>

The following C fragments show some of diversity in block comment style:

<div class="mw-highlight mw-highlight-lang-c mw-content-ltr" dir="ltr"><pre>/*

This is the comment body.

*/

</pre></div>

<div class="mw-highlight mw-highlight-lang-c mw-content-ltr" dir="ltr"><pre>/*****************************

* *

* This is the comment body. *

* *

*****************************/

</pre></div>

Factors such as personal preference, flexibility of programming tools can influence the commenting style used. For example, the first might be preferred by programmers who use a <a href="Source_code_editor" class="mw-redirect" title="Source code editor">source code editor</a> that does not automatically format a comment as shown in the second example.

Software consultant and technology commentator <a href="Allen_Holub" title="Allen Holub">Allen Holub</a><a href="#cite_note-Holub000-35">[35]</a> advocates aligning the left edges of comments:<a href="#cite_note-Holub001-36">[36]</a>

<div class="mw-highlight mw-highlight-lang-c mw-content-ltr" dir="ltr"><pre> /* This is the style recommended by Holub for C and C++.

* It is demonstrated in ''Enough Rope'', in rule 29.

*/

</pre></div>

<div class="mw-highlight mw-highlight-lang-c mw-content-ltr" dir="ltr"><pre> /* This is another way to do it, also in C.

** It is easier to do in editors that do not automatically indent the second

** through last lines of the comment one space from the first.

** It is also used in Holub's book, in rule 31.

*/

</pre></div>

In many languages, a line comment can follow program code such that the comment is inline and generally describes the code to the left of it. For example, in this Perl:

<div class="mw-highlight mw-highlight-lang-perl mw-content-ltr" dir="ltr"><pre>print $s . "\n"; # Add a newline character after printing

</pre></div>

If a language supports both line and block comments, programming teams may decide upon a convention of when to use which. For example, line comments only for minor comments, and block comments to for higher-level abstractions.

Programmers often use one of select words – also known as <a href="Tag_(metadata)" title="Tag (metadata)">tags</a>, codetags<a href="#cite_note-37">[37]</a><a href="#cite_note-38">[38]</a> and tokens<a href="#cite_note-39">[39]</a> – to categorize the information in a comment. Programmers may leverage these tags by searching for them via a <a href="Text_editor" title="Text editor">text editor</a> or <a href="Grep" title="Grep">grep</a>. Some editors <a href="Syntax_highlighting" title="Syntax highlighting">highlight</a> comment text based on tags.

Commonly used tags include:

<ul><li>BUG, DEBUG — identifies a known <a href="Software_bug" title="Software bug">bug</a>; maybe implying it should be fixed</li>

<li>FIXME — implies that there is work to do to fix a bug</li>

<li>HACK, BODGE, KLUDGE — marks a solution that might be considered low quality</li>

<li>TODO — describes some work to do</li>

<li>NOTE — relatively general information</li>

<li>UNDONE — a reversal or "roll back" of previous code</li></ul>

For example:

<pre>int foo() {

// TODO implement

}

</pre>

<div class="mw-heading mw-heading2"><h2 id="Examples">Examples</h2></div>

Syntax for comments varies by programming language. There are common patterns used by multiple languages while also a wide range of syntax among the languages in general. To limit the length of this section, some examples are grouped by languages with the same or very similar syntax. Others are for particular languages that have less common syntax.

<div class="mw-heading mw-heading3"><h3 id="Curly_brace_languages">Curly brace languages</h3></div>

Many of the <a href="Curly_brace_language" class="mw-redirect" title="Curly brace language">curly brace languages</a> such as C, C++ and their many derivatives delimit a line comment with <code class="mw-highlight mw-highlight-lang-text mw-content-ltr" style="" dir="ltr">//</code> and a block comment with <code class="mw-highlight mw-highlight-lang-text mw-content-ltr" style="" dir="ltr">/*</code> and <code class="mw-highlight mw-highlight-lang-text mw-content-ltr" style="" dir="ltr">*/</code>. Originally, C lacked the line comment, but it was added in <a href="C99" title="C99">C99</a>. Notable languages include: C, C++, <a href="C#_(programming_language)" title="C">C#</a>, <a href="D_(programming_language)" title="D (programming language)">D</a>, <a href="Java_(programming_language)" title="Java (programming language)">Java</a>, <a href="JavaScript" title="JavaScript">JavaScript</a> and <a href="Swift_(programming_language)" title="Swift (programming language)">Swift</a>. For example:

<div class="mw-highlight mw-highlight-lang-c mw-content-ltr" dir="ltr"><pre>/*

* Check if over maximum process limit, but be sure to exclude root.

* This is needed to make it possible for login to set per-user

* process limit to something lower than processes root is running.

*/

bool isOverMaximumProcessLimit() {

// TODO implement

}

</pre></div>

Some languages, including D and Swift, allow blocks to be nested while other do not, including C and C++.

An example of nested blocks in D:

<div class="mw-highlight mw-highlight-lang-d mw-content-ltr" dir="ltr"><pre>// line comment

/*

block comment

*/

/+ start of outer block

/+ inner block +/

end of outer block +/

</pre></div>

An example of nested blocks in Swift:

<div class="mw-highlight mw-highlight-lang-swift mw-content-ltr" dir="ltr"><pre>/* This is the start of the outer comment.

/* This is the nested comment. */

This is the end of the outer comment. */

</pre></div>

<div class="mw-heading mw-heading3"><h3 id="Scripting">Scripting</h3></div>

A pattern in many <a href="Scripting_language" title="Scripting language">scripting languages</a> is to delimit a line comment with <code>#</code>. Support for a block comment varies. Notable languages include: <a href="Bash_(Unix_shell)" title="Bash (Unix shell)">Bash</a>, <a href="Raku_(programming_language)" title="Raku (programming language)">Raku</a>, <a href="Ruby_(programming_language)" title="Ruby (programming language)">Ruby</a>, <a href="Perl" title="Perl">Perl</a>, <a href="Windows_PowerShell" class="mw-redirect" title="Windows PowerShell">PowerShell</a>, <a href="Python_(programming_language)" title="Python (programming language)">Python</a> and <a href="R_(programming_language)" title="R (programming language)">R</a>.

An example in R:

<div class="mw-highlight mw-highlight-lang-r mw-content-ltr" dir="ltr"><pre># This is a comment

print("This is not a comment") # This is another comment

</pre></div>

<div class="mw-heading mw-heading4"><h4 id="Block_in_Ruby">Block in Ruby</h4></div>

A block comment is delimited by <code>=begin</code> and <code>=end</code> that start a line. For example:

<div class="mw-highlight mw-highlight-lang-ruby mw-content-ltr" dir="ltr"><pre>puts "not a comment"

# this is a comment

puts "not a comment"

=begin

whatever goes in these lines

is just for the human reader

=end

puts "not a comment"

</pre></div>

<div class="mw-heading mw-heading4"><h4 id="Block_in_Perl">Block in Perl</h4></div>

Instead of a regular block commenting construct, Perl uses <a href="Literate_programming" title="Literate programming">literate programming</a> <a href="Plain_Old_Documentation" title="Plain Old Documentation">plain old documentation (POD)</a> markup.<a href="#cite_note-40">[40]</a> For example:<a href="#cite_note-41">[41]</a>

<div class="mw-highlight mw-highlight-lang-perl mw-content-ltr" dir="ltr"><pre>=item Pod::List-E<gt>new()

Create a new list object. Properties may be specified through a hash

reference like this:

my $list = Pod::List->new({ -start => $., -indent => 4 });

=cut

sub new {

...

}

</pre></div>

Raku (previously called Perl 6) uses the same line comments and POD comments as <a href="Perl" title="Perl">Perl</a>, but adds a configurable block comment type: "multi-line / embedded comments".<a href="#cite_note-perl6-42">[42]</a> It starts with <code>#`</code> and then an opening bracket character and ends with the matching closing bracket character.<a href="#cite_note-perl6-42">[42]</a> For example:

<div class="mw-highlight mw-highlight-lang-perl6 mw-content-ltr" dir="ltr"><pre>#`{{ "commenting out" this version

toggle-case(Str:D $s)

Toggles the case of each character in a string:

my Str $toggled-string = toggle-case("mY NAME IS mICHAEL!");

}}

sub toggle-case(Str:D $s) #`( this version of parens is used now ){

...

}

</pre></div>

<div class="mw-heading mw-heading4"><h4 id="Block_in_PowerShell">Block in PowerShell</h4></div>

PowerShell supports a block comment delimited by <code><#</code> and <code>#></code>. For example:

<div class="mw-highlight mw-highlight-lang-powershell mw-content-ltr" dir="ltr"><pre># Single line comment

<# Multi

Line

Comment #>

</pre></div>

<div class="mw-heading mw-heading4"><h4 id="Block_in_Python">Block in Python</h4></div>

Although Python does not provide for block comments<a href="#cite_note-triple-43">[43]</a> a bare <a href="String_literal" title="String literal">string literal</a> represented by a triple-quoted string is often used for this purpose.<a href="#cite_note-44">[44]</a><a href="#cite_note-triple-43">[43]</a> In the examples below, the triple double-quoted strings act like comments, but are also treated as <a href="Docstring" title="Docstring">docstrings</a>:

<div class="mw-highlight mw-highlight-lang-python mw-content-ltr" dir="ltr"><pre>"""

At the top of a file, this is the module docstring

"""

class MyClass:

"""Class docstring"""

def my_method(self):

"""Method docstring"""

</pre></div>

<div class="mw-heading mw-heading3"><h3 id="Browser_markup">Browser markup</h3></div>

Markup languages in general vary in comment syntax, but some of the notable internet markup formats such as <a href="HTML" title="HTML">HTML</a> and <a href="XML" title="XML">XML</a> delimit a block comment with <code></code> and provide no line comment support. An example in XML:

</pre></div>

For compatibility with <a href="SGML" class="mw-redirect" title="SGML">SGML</a>, double-hyphen (--) is not allowed inside comments.

<a href="ColdFusion" class="mw-redirect" title="ColdFusion">ColdFusion</a> provides syntax similar to the <a href="HTML_comment" class="mw-redirect" title="HTML comment">HTML comment</a>, but uses three dashes instead of two. CodeFusion allows for nested block comments.

<div class="mw-heading mw-heading3"><h3 id="Double_dash">Double dash</h3></div>

A relatively loose collection of languages use <code>--</code> for a single line comment. Notable languages include: <a href="Ada_(programming_language)" title="Ada (programming language)">Ada</a>, <a href="Eiffel_(programming_language)" title="Eiffel (programming language)">Eiffel</a>, <a href="Haskell_(programming_language)" class="mw-redirect" title="Haskell (programming language)">Haskell</a>, <a href="Lua_(programming_language)" class="mw-redirect" title="Lua (programming language)">Lua</a>, <a href="SQL" title="SQL">SQL</a> and <a href="VHDL" title="VHDL">VHDL</a>. Block comment support varies. An example in Ada:

<div class="mw-highlight mw-highlight-lang-ada mw-content-ltr" dir="ltr"><pre>-- the air traffic controller task takes requests for takeoff and landing

task type Controller (My_Runway: Runway_Access) is

-- task entries for synchronous message passing

entry Request_Takeoff (ID: in Airplane_ID; Takeoff: out Runway_Access);

entry Request_Approach(ID: in Airplane_ID; Approach: out Runway_Access);

end Controller;

</pre></div>

<div class="mw-heading mw-heading4"><h4 id="Block_in_Haskell">Block in Haskell</h4></div>

In Haskell, a block comment is delimited by <code>{-</code> and <code>-}</code>. For example:

<div class="mw-highlight mw-highlight-lang-haskell mw-content-ltr" dir="ltr"><pre>{- this is a comment

on more lines -}

-- and this is a comment on one line

putStrLn "Wikipedia" -- this is another comment

</pre></div>

Haskell also provides a <a href="Literate_programming" title="Literate programming">literate programming</a> method of commenting known as "Bird Style".<a href="#cite_note-45">[45]</a> Lines starting with <code>></code> are interpreted as code and everything else is considered a comment. One additional requirement is a blank line before and after the code block:

<div class="mw-highlight mw-highlight-lang-lhaskell mw-content-ltr" dir="ltr"><pre>In Bird-style you have to leave a blank before the code.

> fact :: Integer -> Integer

> fact 0 = 1

> fact (n+1) = (n+1) * fact n

And you have to leave a blank line after the code as well.

</pre></div>

Literate programming can also be accomplished via <a href="LaTeX" title="LaTeX">LaTeX</a>. Example of a definition:

<div class="mw-highlight mw-highlight-lang-lhaskell mw-content-ltr" dir="ltr"><pre>\usepackage{verbatim}

\newenvironment{code}{\verbatim}{\endverbatim}

</pre></div>

Used as follows:

<div class="mw-highlight mw-highlight-lang-lhaskell mw-content-ltr" dir="ltr"><pre>% the LaTeX source file

The \verb|fact n| function call computes $n!$ if $n\ge 0$, here is a definition:\\

\begin{code}

fact :: Integer -> Integer

fact 0 = 1

fact (n+1) = (n+1) * fact n

\end{code}

Here more explanation using \LaTeX{} markup

</pre></div>

<div class="mw-heading mw-heading4"><h4 id="Block_in_Lua">Block in Lua</h4></div>

Lua supports block comments delimited by <code>--[[</code> and <code>]]</code><a href="#cite_note-46">[46]</a> For example:

<div class="mw-highlight mw-highlight-lang-lua mw-content-ltr" dir="ltr"><pre>--[[A multi-line

long comment

]]

</pre></div>

<div class="mw-heading mw-heading4"><h4 id="Block_in_SQL">Block in SQL</h4></div>

In some variants of SQL, the curly brace language block comment (<code>/**/</code>) is supported. Variants include: <a href="Transact-SQL" title="Transact-SQL">Transact-SQL</a>, <a href="MySQL" title="MySQL">MySQL</a>, <a href="SQLite" title="SQLite">SQLite</a>, <a href="PostgreSQL" title="PostgreSQL">PostgreSQL</a>, and <a href="Oracle_Database" title="Oracle Database">Oracle</a>.<a href="#cite_note-MSSQL-47">[47]</a><a href="#cite_note-MySQL-48">[48]</a><a href="#cite_note-SQLite-49">[49]</a><a href="#cite_note-PostgreSQL-50">[50]</a><a href="#cite_note-Oracle-51">[51]</a>

MySQL also supports a line comment delimited by <code>#</code>.

<div class="mw-heading mw-heading3"><h3 id="Less_common_syntax">Less common syntax</h3></div>

<a href="APL_(programming_language)" title="APL (programming language)">APL</a> uses <code>⍝</code> ("lamp") for a line comment. For example:

<div class="mw-highlight mw-highlight-lang-apl mw-content-ltr" dir="ltr"><pre>⍝ Now add the numbers:

c←a+b ⍝ addition

</pre></div>

In dialects that have the <code>⊣</code> ("left") and <code>⊢</code> ("right") primitives, comments can often be inside or separate statements, in the form of ignored strings:

<div class="mw-highlight mw-highlight-lang-apl mw-content-ltr" dir="ltr"><pre>d←2×c ⊣'where'⊢ c←a+ 'bound'⊢ b

</pre></div>

<div class="mw-heading mw-heading4"><h4 id="AppleScript">AppleScript</h4></div>

<a href="AppleScript" title="AppleScript">AppleScript</a> supports both line and block comments. For example:

<div class="mw-highlight mw-highlight-lang-applescript mw-content-ltr" dir="ltr"><pre># line comment (in later versions)

(*

This program displays a greeting.

*)

on greet(myGreeting)

display dialog myGreeting & " world!"

end greet

-- Show the greeting

greet("Hello")

</pre></div>

<div class="mw-heading mw-heading4"><h4 id="BASIC">BASIC</h4></div>

Early versions of <a href="BASIC" title="BASIC">BASIC</a> used <code class="mw-highlight mw-highlight-lang-text mw-content-ltr" style="" dir="ltr">REM</code> (short for remark) for a line comment.

<div class="mw-highlight mw-highlight-lang-basic mw-content-ltr" dir="ltr"><pre>10 REM This BASIC program shows the use of the PRINT and GOTO Statements.

15 REM It fills the screen with the phrase "HELLO"

20 PRINT "HELLO"

30 GOTO 20

</pre></div>

In later variations, including <a href="Quick_Basic" class="mw-redirect" title="Quick Basic">Quick Basic</a>, <a href="Q_Basic" class="mw-redirect" title="Q Basic">Q Basic</a>, <a href="Visual_Basic" title="Visual Basic">Visual Basic</a> (VB), <a href="Visual_Basic_.NET" class="mw-redirect" title="Visual Basic .NET">VB.NET</a>, <a href="VBScript" title="VBScript">VBScript</a>, <a href="FreeBASIC" title="FreeBASIC">FreeBASIC</a> and <a href="Gambas" title="Gambas">Gambas</a>, a line comment is delimited with <code>'</code> (apostrophe). An example in VB.NET:

<div class="mw-highlight mw-highlight-lang-vbnet mw-content-ltr" dir="ltr"><pre>Public Class Form1

Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click

' new style line comment

rem old style line comment still supported

MessageBox.Show("Hello, World") ' show dialog with a greeting

End Sub

End Class

</pre></div>

<div class="mw-heading mw-heading4"><h4 id="Cisco_IOS_and_IOS-XE_configuration">Cisco IOS and IOS-XE configuration</h4></div>

The <a href="Exclamation_point" class="mw-redirect" title="Exclamation point">exclamation point</a> (!) may be used to mark comments in a Cisco router's configuration mode, however such comments are not saved to <a href="Non-volatile_memory" title="Non-volatile memory">non-volatile memory</a> (which contains the startup-config), nor are they displayed by the "show run" command.<a href="#cite_note-52">[52]</a><a href="#cite_note-53">[53]</a>

It is possible to insert <a href="Human-readable" class="mw-redirect" title="Human-readable">human-readable</a> content that is actually part of the configuration, and may be saved to the <a href="NVRAM" class="mw-redirect" title="NVRAM">NVRAM</a> startup-config via:

<ul><li>The "description" command, used to add a description to the configuration of an interface or of a <a href="BGP" class="mw-redirect" title="BGP">BGP</a> neighbor</li>

<li>The "name" parameter, to add a remark to a static route</li>

<li>The "remark" command in access lists</li></ul>

<div class="mw-highlight mw-highlight-lang-text mw-content-ltr" dir="ltr"><pre>! Paste the text below to reroute traffic manually

config t

int gi0/2

no shut

ip route 0.0.0.0 0.0.0.0 gi0/2 name ISP2

no ip route 0.0.0.0 0.0.0.0 gi0/1 name ISP1

int gi0/1

shut

exit

</pre></div>

<div class="mw-heading mw-heading4"><h4 id="Fortran">Fortran</h4></div>

The following fixed-form <a href="Fortran" title="Fortran">Fortran</a> code fragment shows that comment syntax is column-oriented. A letter <code>C</code> in the first column causes the entire line to be treated as a comment. In <a href="Fortran_77" class="mw-redirect" title="Fortran 77">Fortran 77</a>, an asterisk in column 1 also indicates a comment.

<div class="mw-highlight mw-highlight-lang-fortranfixed mw-content-ltr" dir="ltr"><pre>C

C Lines beginning with 'C' in the first (a.k.a. comment) column are comments

C

WRITE (6,610)

610 FORMAT(12H HELLO WORLD)

END

</pre></div>

The following <a href="Fortran" title="Fortran">Fortran 90</a> code fragment shows a more modern line comment syntax; text following <code>!</code>.

<div class="mw-highlight mw-highlight-lang-fortran mw-content-ltr" dir="ltr"><pre>! A comment

program comment_test

print '(A)', 'Hello world' ! also a comment

end program

</pre></div>

Free-form Fortran, also introduced with Fortran 90, only supports this latter style of comment.

Although not a part of the Fortran Standard, many Fortran compilers offer an optional C-like <a href="Preprocessor" title="Preprocessor">preprocessor</a> pass. This can be used to provide block comments:

<div class="mw-highlight mw-highlight-lang-fortran mw-content-ltr" dir="ltr"><pre>#if 0

This is a block comment spanning

multiple lines.

#endif

program comment_test

end program

</pre></div>

<div class="mw-heading mw-heading4"><h4 id="MATLAB">MATLAB</h4></div>

In <a href="MATLAB" title="MATLAB">MATLAB</a>'s programming language, the '%' character indicates a single-line comment. Multi line comments are also available via %{ and %} brackets and can be nested, e.g.

<div class="mw-highlight mw-highlight-lang-matlab mw-content-ltr" dir="ltr"><pre>% These are the derivatives for each term

d = [0 -1 0];

%{

%{

(Example of a nested comment, indentation is for cosmetics (and ignored).)

%}

We form the sequence, following the Taylor formula.

Note that we're operating on a vector.

%}

seq = d .* (x - c).^n ./(factorial(n))

% We add-up to get the Taylor approximation

approx = sum(seq)

</pre></div>

<a href="Nim_(programming_language)" title="Nim (programming language)">Nim</a> delimits a line comment with <code>#</code> and block comments with <code>#[</code> and <code>]#</code>. Block comments can be nested.

Nim also has documentation comments that use mixed <a href="Markdown" title="Markdown">Markdown</a> and <a href="ReStructuredText" title="ReStructuredText">ReStructuredText</a> markups.

A line documentation comment uses '##' and a block documentation comment uses '##[' and ']##'.

The compiler can generate <a href="HTML" title="HTML">HTML</a>, <a href="LaTeX" title="LaTeX">LaTeX</a> and <a href="JSON" title="JSON">JSON</a> documentation from the documentation comments.

Documentation comments are part of the <a href="Abstract_syntax_tree" title="Abstract syntax tree">abstract syntax tree</a> and can be extracted using macros.<a href="#cite_note-54">[54]</a>

<div class="mw-highlight mw-highlight-lang-nim mw-content-ltr" dir="ltr"><pre>## Documentation of the module *ReSTructuredText* and **MarkDown**

# This is a comment, but it is not a documentation comment.

type Kitten = object ## Documentation of type

age: int ## Documentation of field

proc purr(self: Kitten) =

## Documentation of function

echo "Purr Purr" # This is a comment, but it is not a documentation comment.

# This is a comment, but it is not a documentation comment.

</pre></div>

<div class="mw-heading mw-heading4"><h4 id="OCaml">OCaml</h4></div>

<a href="OCaml" title="OCaml">OCaml</a> supports nestable comments. For example:

<div class="mw-highlight mw-highlight-lang-ocaml mw-content-ltr" dir="ltr"><pre>codeLine(* comment level 1(*comment level 2*)*)

</pre></div>

<div class="mw-heading mw-heading4"><h4 id="Pascal,_Delphi">Pascal, Delphi</h4></div>

In <a href="Pascal_(programming_language)" title="Pascal (programming language)">Pascal</a> and <a href="Delphi_(software)" title="Delphi (software)">Delphi</a>, a block comment is delimited by <code>{</code> and <code>}</code>, and as an alternative for computers that do not support these characters, <code>(*</code> and <code>*)</code> are also supported. A line comment is delimited by <code>\\</code>.<a href="#cite_note-55">[55]</a> In <a href="Niklaus_Wirth" title="Niklaus Wirth">Niklaus Wirth</a>'s more modern family of languages (including <a href="Modula-2" title="Modula-2">Modula-2</a> and <a href="Oberon_(programming_language)" title="Oberon (programming language)">Oberon</a>), comments are delimited by <code>(*</code> and <code>*)</code>.<a href="#cite_note-56">[56]</a><a href="#cite_note-57">[57]</a> Comments can be nested. For example:

<div class="mw-highlight mw-highlight-lang-pascal mw-content-ltr" dir="ltr"><pre>(* test diagonals *)

columnDifference := testColumn - column;

if (row + columnDifference = testRow) or

.......

</pre></div>

Comments in <a href="PHP" title="PHP">PHP</a> can be either curly brace style (both line and block), or line delimited with <code>#</code>l. Blocks cannot be nested. Starting in PHP 8, a <code>#</code> only means comment if it's not immediately followed by <code>[</code>. Otherwise, it delimits an attribute, which continues till the next <code>]</code>. For example:

<div class="mw-highlight mw-highlight-lang-php mw-content-ltr" dir="ltr"><pre>/**

* This class contains a sample documentation.

* @author Unknown

*/

#[Attribute]

class MyAttribute {

const VALUE = 'value';

// C++ style line comment

private $value;

# script style line comment

public function __construct($value = null) {

$this->value = $value;

}

</pre></div>

<div class="mw-heading mw-heading2"><h2 id="Security_issues">Security issues</h2></div>

In <a href="Interpreted_language" class="mw-redirect" title="Interpreted language">interpreted languages</a> the comments are viewable to the end user of the program. In some cases, such as sections of code that are "commented out", this may present a security <a href="Vulnerability_(computing)" class="mw-redirect" title="Vulnerability (computing)">vulnerability</a>.<a href="#cite_note-InsecureComments-58">[58]</a>

<ul><li><a href="Comparison_of_programming_languages_(syntax)#Comments" title="Comparison of programming languages (syntax)">Comparison of programming languages (syntax)#Comments</a></li></ul>

<div class="mw-heading mw-heading2"><h2 id="Notes_and_references">Notes and references</h2></div>

/* start https://en.wikipedia.org/ */

.mw-parser-output .reflist{margin-bottom:0.5em;list-style-type:decimal}@media screen{.mw-parser-output .reflist{font-size:90%}}.mw-parser-output .reflist .references{font-size:100%;margin-bottom:0;list-style-type:inherit}.mw-parser-output .reflist-columns-2{column-width:30em}.mw-parser-output .reflist-columns-3{column-width:25em}.mw-parser-output .reflist-columns{margin-top:0.3em}.mw-parser-output .reflist-columns ol{margin-top:0}.mw-parser-output .reflist-columns li{page-break-inside:avoid;break-inside:avoid-column}.mw-parser-output .reflist-upper-alpha{list-style-type:upper-alpha}.mw-parser-output .reflist-upper-roman{list-style-type:upper-roman}.mw-parser-output .reflist-lower-alpha{list-style-type:lower-alpha}.mw-parser-output .reflist-lower-greek{list-style-type:lower-greek}.mw-parser-output .reflist-lower-roman{list-style-type:lower-roman}

/* end https://en.wikipedia.org/ */

</style><div class="reflist reflist-columns references-column-width reflist-columns-2">

/* start https://en.wikipedia.org/ */

.mw-parser-output cite.citation{font-style:inherit;word-wrap:break-word}.mw-parser-output .citation q{quotes:"\"""\"""'""'"}.mw-parser-output .citation:target{background-color:rgba(0,127,255,0.133)}.mw-parser-output .id-lock-free.id-lock-free a{background:url("./mw/Lock-green.svg")right 0.1em center/9px no-repeat}.mw-parser-output .id-lock-limited.id-lock-limited a,.mw-parser-output .id-lock-registration.id-lock-registration a{background:url("./mw/Lock-gray-alt-2.svg")right 0.1em center/9px no-repeat}.mw-parser-output .id-lock-subscription.id-lock-subscription a{background:url("./mw/Lock-red-alt-2.svg")right 0.1em center/9px no-repeat}.mw-parser-output .cs1-ws-icon a{background:url("./mw/Wikisource-logo.svg")right 0.1em center/12px no-repeat}body:not(.skin-timeless):not(.skin-minerva) .mw-parser-output .id-lock-free a,body:not(.skin-timeless):not(.skin-minerva) .mw-parser-output .id-lock-limited a,body:not(.skin-timeless):not(.skin-minerva) .mw-parser-output .id-lock-registration a,body:not(.skin-timeless):not(.skin-minerva) .mw-parser-output .id-lock-subscription a,body:not(.skin-timeless):not(.skin-minerva) .mw-parser-output .cs1-ws-icon a{background-size:contain;padding:0 1em 0 0}.mw-parser-output .cs1-code{color:inherit;background:inherit;border:none;padding:inherit}.mw-parser-output .cs1-hidden-error{display:none;color:var(--color-error,#d33)}.mw-parser-output .cs1-visible-error{color:var(--color-error,#d33)}.mw-parser-output .cs1-maint{display:none;color:#085;margin-left:0.3em}.mw-parser-output .cs1-kern-left{padding-left:0.2em}.mw-parser-output .cs1-kern-right{padding-right:0.2em}.mw-parser-output .citation .mw-selflink{font-weight:inherit}@media screen{.mw-parser-output .cs1-format{font-size:95%}html.skin-theme-clientpref-night .mw-parser-output .cs1-maint{color:#18911f}}@media screen and (prefers-color-scheme:dark){html.skin-theme-clientpref-os .mw-parser-output .cs1-maint{color:#18911f}}

/* end https://en.wikipedia.org/ */

</style><cite id="CITEREFPenny_Grubb2003" class="citation book cs1">Penny Grubb, Armstrong Takang (2003). Software Maintenance: Concepts and Practice. World Scientific. pp. 7, plese start120–121. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-981-238-426-3</bdi>.</cite>

</li>

<li id="cite_note-2"><a href="#cite_ref-2">^</a> <cite id="CITEREFGanguli2002" class="citation book cs1">Ganguli, Madhushree (2002). Making Use of Jsp. New York: Wiley. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-0-471-21974-3</bdi>.</cite>, <cite id="CITEREFHewitt2003" class="citation book cs1">Hewitt, Eben (2003). Java for Coldfusion Developers. Upper Saddle River: Pearson Education. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-0-13-046180-3</bdi>.</cite>

</li>

<li id="cite_note-Dietrich000-3"><a href="#cite_ref-Dietrich000_3-0">^</a> <cite id="CITEREFW._R.2003" class="citation book cs1">W. R., Dietrich (2003). Applied Pattern Recognition: Algorithms and Implementation in C++. Springer. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-3-528-35558-6</bdi>.</cite> offers viewpoints on proper use of comments in source code. p. 66.

</li>

<li id="cite_note-Keyes000-4"><a href="#cite_ref-Keyes000_4-0">^</a> <cite id="CITEREFKeyes2003" class="citation book cs1">Keyes, Jessica (2003). Software Engineering Handbook. CRC Press. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-0-8493-1479-7</bdi>.</cite> discusses comments and the "Science of Documentation" p. 256.

</li>

<li id="cite_note-Higham000-5"><a href="#cite_ref-Higham000_5-0">^</a> <cite id="CITEREFHigham2005" class="citation book cs1">Higham, Desmond (2005). MATLAB Guide. SIAM. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-0-89871-578-1</bdi>.</cite>

</li>

<li id="cite_note-Vermeulen000-6"><a href="#cite_ref-Vermeulen000_6-0">^</a> <cite id="CITEREFVermeulen2000" class="citation book cs1">Vermeulen, Al (2000). <a rel="nofollow" class="external text" href="https://archive.org/details/elementsofjavast00verm">The Elements of Java Style</a>. Cambridge University Press. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-0-521-77768-1</bdi>.</cite>

</li>

<li id="cite_note-javadude000-7">^ <a href="#cite_ref-javadude000_7-0">a</a> <a href="#cite_ref-javadude000_7-1">b</a> <a href="#cite_ref-javadude000_7-2">c</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="http://javadude.com/articles/comments.html">"Using the right comment in Java"</a>. 2000-03-04. Retrieved 2007-07-24.</cite>

</li>

<li id="cite_note-JBDixit000-8"><a href="#cite_ref-JBDixit000_8-0">^</a> <cite id="CITEREFDixit2003" class="citation book cs1">Dixit, J.B. (2003). Computer Fundamentals and Programming in C. Laxmi Publications. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-81-7008-882-0</bdi>.</cite>

</li>

<li id="cite_note-BadComment000-9">^ <a href="#cite_ref-BadComment000_9-0">a</a> <a href="#cite_ref-BadComment000_9-1">b</a> <a href="#cite_ref-BadComment000_9-2">c</a> <a href="The_Elements_of_Programming_Style_(book)" class="mw-redirect" title="The Elements of Programming Style (book)">The Elements of Programming Style</a>, <a href="Brian_Kernighan" title="Brian Kernighan">Kernighan</a> & <a href="P._J._Plauger" title="P. J. Plauger">Plauger</a>

</li>

<li id="cite_note-GoodComment000-10">^ <a href="#cite_ref-GoodComment000_10-0">a</a> <a href="#cite_ref-GoodComment000_10-1">b</a> <a href="Code_Complete" title="Code Complete">Code Complete</a>, <a href="Steve_McConnell" title="Steve McConnell">McConnell</a>

</li>

<li id="cite_note-AlgoComments-11"><a href="#cite_ref-AlgoComments_11-0">^</a> <cite id="CITEREFSpinellis2003" class="citation book cs1">Spinellis, Diomidis (2003). Code reading: The Open Source Perspective. Addison-Wesley. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-0-201-79940-8</bdi>.</cite>

</li>

<li id="cite_note-12"><a href="#cite_ref-12">^</a> See e.g., <cite id="CITEREFWynne-Powell2008" class="citation book cs1">Wynne-Powell, Rod (2008). <a rel="nofollow" class="external text" href="https://archive.org/details/macosxforphotogr0000wynn">Mac OS X for Photographers: Optimized Image Workflow for the Mac User</a>. Oxford: Focal Press. p. 243. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-0-240-52027-8</bdi>.</cite>

</li>

<li id="cite_note-13"><a href="#cite_ref-13">^</a> See e.g., <cite id="CITEREFBerlin2006" class="citation book cs1">Berlin, Daniel (2006). Practical Subversion, Second Edition. Berkeley: APress. p. 168. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-1-59059-753-8</bdi>.</cite>

</li>

<li id="cite_note-14"><a href="#cite_ref-14">^</a> <cite id="CITEREFLamb1998" class="citation book cs1">Lamb, Linda (1998). <a rel="nofollow" class="external text" href="https://archive.org/details/learningvieditor00lamb">Learning the VI Editor</a>. Sebastopol: O'Reilly & Associates. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-1-56592-426-0</bdi>.</cite>

</li>

<li id="cite_note-Ambler000-15"><a href="#cite_ref-Ambler000_15-0">^</a> <cite id="CITEREFAmbler2004" class="citation book cs1">Ambler, Scott (2004). The Object Primer: Agile Model-Driven Development with UML 2.0. Cambridge University Press. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-1-397-80521-8</bdi>.</cite>

</li>

<li id="cite_note-16"><a href="#cite_ref-16">^</a> <a rel="nofollow" class="external text" href="https://clojure.github.io/clojure/clojure.core-api.html#clojure.core/defn">Function definition with docstring in Clojure</a>

</li>

<li id="cite_note-17"><a href="#cite_ref-17">^</a> <cite id="CITEREFMurach" class="citation book cs1">Murach. C# 2005. p. 56.</cite>

</li>

<li id="cite_note-asciiart000-18"><a href="#cite_ref-asciiart000_18-0">^</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://web.archive.org/web/20070714092702/http://www.codeproject.com/macro/codeplotter.asp">"CodePlotter 1.6 – Add and edit diagrams in your code with this 'Visio-like' tool"</a>. Archived from <a rel="nofollow" class="external text" href="http://www.codeproject.com/macro/codeplotter.asp">the original</a> on 2007-07-14. Retrieved 2007-07-24.</cite>

</li>

<li id="cite_note-Niederst000-19">^ <a href="#cite_ref-Niederst000_19-0">a</a> <a href="#cite_ref-Niederst000_19-1">b</a> <cite id="CITEREFNiederst2006" class="citation book cs1">Niederst, Jennifer (2006). Web Design in a Nutshell: A Desktop Quick Reference. O'Reilly. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-0-596-00987-8</bdi>.</cite>

Sometimes the difference between a "comment" and other syntax elements of a programming or markup language entails subtle nuances. Niederst indicates one such situation by stating: "Unfortunately, XML software thinks of comments as unimportant information and may simply remove the comments from a document before processing it. To avoid this problem, use an XML CDATA section instead."

</li>

<li id="cite_note-20"><a href="#cite_ref-20">^</a> <a href="https://wiki.c2.com/?HotComments" class="extiw external" title="c2:HotComments">c2: HotComments</a>

</li>

<li id="cite_note-21"><a href="#cite_ref-21">^</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://docs.ruby-lang.org/en/2.4.0/Encoding.html">"class Encoding"</a>. Ruby. ruby-lang.org. Retrieved 5 December 2018.</cite>

</li>

<li id="cite_note-22"><a href="#cite_ref-22">^</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://www.python.org/dev/peps/pep-0263/">"PEP 263 – Defining Python Source Code Encodings"</a>. Python.org. Retrieved 5 December 2018.</cite>

</li>

<li id="cite_note-23"><a href="#cite_ref-23">^</a> <cite id="CITEREFPolacek2017" class="citation web cs1">Polacek, Marek (2017-03-10). <a rel="nofollow" class="external text" href="https://developers.redhat.com/blog/2017/03/10/wimplicit-fallthrough-in-gcc-7/">"-Wimplicit-fallthrough in GCC 7"</a>. Red Hat Developer. Red Hat. Retrieved 10 February 2019.</cite>

</li>

<li id="cite_note-24"><a href="#cite_ref-24">^</a> <cite id="CITEREFLisa_Eadicicco2014" class="citation web cs1">Lisa Eadicicco (27 March 2014). <a rel="nofollow" class="external text" href="https://www.businessinsider.com/microsoft-hidden-messages-in-word-and-ms-dos-2014-3?r=US&IR=T">"Microsoft Programmers Hid A Bunch Of Profanity In Early Software Code"</a>. <a href="Business_Insider_Australia" class="mw-redirect" title="Business Insider Australia">Business Insider Australia</a>. <a rel="nofollow" class="external text" href="https://web.archive.org/web/20161229170544/http://www.businessinsider.com.au/microsoft-hidden-messages-in-word-and-ms-dos-2014-3?r=US&IR=T">Archived</a> from the original on 29 December 2016.</cite>

</li>

<li id="cite_note-SwearWords-25"><a href="#cite_ref-SwearWords_25-0">^</a> (see e.g., <a rel="nofollow" class="external text" href="http://www.vidarholen.net/contents/wordcount/">Linux Swear Count</a>).

</li>

<li id="cite_note-26"><a href="#cite_ref-26">^</a> <cite id="CITEREFGoodliffe2006" class="citation book cs1">Goodliffe, Pete (2006). Code Craft. San Francisco: No Starch Press. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-1-59327-119-0</bdi>.</cite>

</li>

<li id="cite_note-27"><a href="#cite_ref-27">^</a> <cite id="CITEREFSmith1991" class="citation book cs1">Smith, T. (1991). Intermediate Programming Principles and Techniques Using Pascal. Belmont: West Pub. Co. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-0-314-66314-6</bdi>.</cite>

</li>

<li id="cite_note-28"><a href="#cite_ref-28">^</a> See e.g., <cite id="CITEREFKoletzke2000" class="citation book cs1">Koletzke, Peter (2000). Oracle Developer Advanced Forms & Reports. Berkeley: Osborne/McGraw-Hill. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-0-07-212048-6</bdi>.</cite> page 65.

</li>

<li id="cite_note-BadComments001-29"><a href="#cite_ref-BadComments001_29-0">^</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="http://www.sqlservercentral.com/columnists/awarren/worstpracticebadcomments.asp">"Worst Practice - Bad Comments"</a>. Retrieved 2007-07-24.</cite>

</li>

<li id="cite_note-Morelli000-30"><a href="#cite_ref-Morelli000_30-0">^</a> <cite id="CITEREFMorelli2006" class="citation book cs1">Morelli, Ralph (2006). Java, Java, Java: object-oriented problem solving. Prentice Hall College. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-0-13-147434-5</bdi>.</cite>

</li>

<li id="cite_note-Javadoc000-31">^ <a href="#cite_ref-Javadoc000_31-0">a</a> <a href="#cite_ref-Javadoc000_31-1">b</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="http://java.sun.com/j2se/javadoc/writingdoccomments/">"How to Write Doc Comments for the Javadoc Tool"</a>. Retrieved 2007-07-24.</cite> Javadoc guidelines specify that comments are crucial to the platform. Further, the appropriate level of detail is fairly well-defined: "We spend time and effort focused on specifying boundary conditions, argument ranges and corner cases rather than defining common programming terms, writing conceptual overviews, and including examples for developers."

</li>

<li id="cite_note-techniques001-32"><a href="#cite_ref-techniques001_32-0">^</a> <cite id="CITEREFYourdon2007" class="citation book cs1">Yourdon, Edward (2007). Techniques of Program Structure and Design. University of Michigan. 013901702X.</cite>Non-existent comments can make it difficult to comprehend code, but comments may be detrimental if they are obsolete, redundant, incorrect or otherwise make it more difficult to comprehend the intended purpose for the source code.

</li>

<li id="cite_note-CmmtPhilosophy-33"><a href="#cite_ref-CmmtPhilosophy_33-0">^</a> <cite id="CITEREFDewhurst2002" class="citation book cs1">Dewhurst, Stephen C (2002). C++ Gotchas: Avoiding Common Problems in Coding and Design. Addison-Wesley Professional. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-0-321-12518-7</bdi>.</cite>

</li>

<li id="cite_note-gnome000-34"><a href="#cite_ref-gnome000_34-0">^</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://web.archive.org/web/20070808173421/http://developer.gnome.org/doc/guides/programming-guidelines/code-style.html">"Coding Style"</a>. Archived from <a rel="nofollow" class="external text" href="http://developer.gnome.org/doc/guides/programming-guidelines/code-style.html">the original</a> on 2007-08-08. Retrieved 2007-07-24.</cite>

</li>

<li id="cite_note-Holub000-35"><a href="#cite_ref-Holub000_35-0">^</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://web.archive.org/web/20070720153845/http://www.holub.com/company/allen_holub.html">"Allen Holub"</a>. Archived from <a rel="nofollow" class="external text" href="http://www.holub.com/company/allen_holub.html">the original</a> on 2007-07-20. Retrieved 2007-07-24.</cite>

</li>

<li id="cite_note-Holub001-36"><a href="#cite_ref-Holub001_36-0">^</a> Allen Holub, Enough Rope to Shoot Yourself in the Foot, <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>0-07-029689-8</bdi>, 1995, McGraw-Hill

</li>

<li id="cite_note-37"><a href="#cite_ref-37">^</a> <a rel="nofollow" class="external text" href="https://www.python.org/dev/peps/pep-0350/#what-are-codetags">"PEP 0350 – Codetags"</a>, Python Software Foundation

</li>

<li id="cite_note-38"><a href="#cite_ref-38">^</a> <a rel="nofollow" class="external text" href="https://medium.com/@eido.askayo/never-forget-anything-before-after-and-while-coding-98d187ae4cf1">"Never Forget Anything Before, After and While Coding"</a>, Using "codetag" comments as productive remainders

</li>

<li id="cite_note-39"><a href="#cite_ref-39">^</a> <a rel="nofollow" class="external text" href="https://msdn.microsoft.com/en-us/library/txtwdysk.aspx#tokenscomments">"Using the Task List"</a>, msdn.microsoft.com

</li>

<cite class="citation web cs1"><a rel="nofollow" class="external text" href="http://perldoc.perl.org/perlpod.html">"perlpod – the Plain Old Documentation format"</a>. Retrieved 2011-09-12.</cite>

</li>

<cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://search.cpan.org/~bradapp/PodParser-1.20/lib/Pod/ParseUtils.pm">"Pod::ParseUtils – helpers for POD parsing and conversion"</a>. Retrieved 2011-09-12.</cite>

</li>

<cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://docs.perl6.org/language/syntax#Comments">"Perl 6 Documentation – Syntax (Comments)"</a>. Retrieved 2017-04-06.</cite>

</li>

<li id="cite_note-triple-43">^ <a href="#cite_ref-triple_43-0">a</a> <a href="#cite_ref-triple_43-1">b</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://web.archive.org/web/20210819164828/https://www.tutorialdocs.com/tutorial/python3/python3-basic-syntax.html">"Python 3 Basic Syntax"</a>. Archived from <a rel="nofollow" class="external text" href="https://www.tutorialdocs.com/tutorial/python3/python3-basic-syntax.html">the original</a> on 19 August 2021. Retrieved 25 February 2019. <q>Triple quotes are treated as regular strings with the exception that they can span multiple lines. By regular strings I mean that if they are not assigned to a variable they will be immediately garbage collected as soon as that code executes. hence are not ignored by the interpreter in the same way that #a comment is.</q></cite>

</li>

<li id="cite_note-44"><a href="#cite_ref-44">^</a> <a rel="nofollow" class="external text" href="https://twitter.com/gvanrossum/status/112670605505077248">"Python tip: You can use multi-line strings as multi-line comments"</a>, 11 September 2011, Guido van Rossum

</li>

<li id="cite_note-45"><a href="#cite_ref-45">^</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="http://www.haskell.org/haskellwiki/Literate_programming#Bird_Style">"Literate programming"</a>. haskell.org.</cite>

</li>

<li id="cite_note-46"><a href="#cite_ref-46">^</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="http://www.lua.org/pil/1.3.html">"Programming in Lua 1.3"</a>. www.Lua.org. Retrieved 2017-11-08.</cite>

</li>

<li id="cite_note-MSSQL-47"><a href="#cite_ref-MSSQL_47-0">^</a> <cite id="CITEREFTalmage1999" class="citation book cs1">Talmage, Ronald R. (1999). <a rel="nofollow" class="external text" href="https://archive.org/details/microsoftsqlserv00talm">Microsoft SQL Server 7</a>. Prima Publishing. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-0-7615-1389-6</bdi>.</cite>

</li>

<li id="cite_note-MySQL-48"><a href="#cite_ref-MySQL_48-0">^</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://dev.mysql.com/doc/refman/8.0/en/comments.html">"MySQL 8.0 Reference Manual"</a>. Oracle Corporation. Retrieved January 2, 2020.</cite>

</li>

<li id="cite_note-SQLite-49"><a href="#cite_ref-SQLite_49-0">^</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://www.sqlite.org/lang_comment.html">"SQL As Understood By SQLite"</a>. SQLite Consortium. Retrieved January 2, 2020.</cite>

</li>

<li id="cite_note-PostgreSQL-50"><a href="#cite_ref-PostgreSQL_50-0">^</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://www.postgresql.org/docs/10/sql-syntax-lexical.html#SQL-SYNTAX-COMMENTS">"PostgreSQL 10.11 Documentation"</a>. The PostgreSQL Global Development Group. Retrieved January 2, 2020.</cite>

</li>

<li id="cite_note-Oracle-51"><a href="#cite_ref-Oracle_51-0">^</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://docs.oracle.com/cd/B13789_01/server.101/b10759/sql_elements006.htm">"Oracle® Database SQL Reference"</a>. Oracle Corporation. Retrieved January 2, 2020.</cite>

</li>

<li id="cite_note-52"><a href="#cite_ref-52">^</a> <cite class="citation web cs1"><a rel="nofollow" class="external text" href="https://learningnetwork.cisco.com/thread/71302">"Leave a comment in running-config"</a>. Cisco Learning Network (discussion forum).</cite>

</li>

<li id="cite_note-53"><a href="#cite_ref-53">^</a> <cite id="GUID-657D5FD4-32C5-444C-BCE0-BC2CC1069005" class="citation web cs1"><a rel="nofollow" class="external text" href="http://www.cisco.com/c/en/us/td/docs/ios-xml/ios/config-mgmt/configuration/xe-3s/asr903/config-mgmt-xe-3s-asr903-book/cm-config-files.html">"Managing Configuration Files Configuration Guide, Cisco IOS XE Release 3S (ASR 900 Series)"</a>.</cite>

</li>

<li id="cite_note-54"><a href="#cite_ref-54">^</a> <a rel="nofollow" class="external text" href="https://nim-lang.github.io/Nim/macros.html#extractDocCommentsAndRunnables%2CNimNode">macros.extractDocCommentsAndRunnables</a>

</li>

<li id="cite_note-55"><a href="#cite_ref-55">^</a> <cite id="CITEREFKathleen_Jensen,_Niklaus_Wirth1985" class="citation book cs1">Kathleen Jensen, Niklaus Wirth (1985). Pascal User Manual and Report. Springer-Verlag. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>0-387-96048-1</bdi>.</cite>

</li>

<li id="cite_note-56"><a href="#cite_ref-56">^</a> <cite id="CITEREFNiklaus_Wirth1983" class="citation book cs1">Niklaus Wirth (1983). Programming in Modula-2. Springer-Verlag. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>0-387-15078-1</bdi>.</cite>

</li>

<li id="cite_note-57"><a href="#cite_ref-57">^</a> *<cite id="CITEREFMartin_Reiser,_Niklaus_Wirth1992" class="citation book cs1">Martin Reiser, Niklaus Wirth (1992). Programming in Oberon. Addison-Wesley. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>0-201-56543-9</bdi>.</cite>

</li>

<li id="cite_note-InsecureComments-58"><a href="#cite_ref-InsecureComments_58-0">^</a> <cite id="CITEREFAndress2003" class="citation book cs1">Andress, Mandy (2003). Surviving Security: How to Integrate People, Process, and Technology. CRC Press. <a href="ISBN_(identifier)" class="mw-redirect" title="ISBN (identifier)">ISBN</a> <bdi>978-0-8493-2042-2</bdi>.</cite>

</li>

</ol></div>

<div class="mw-heading mw-heading2"><h2 id="Further_reading">Further reading</h2></div>

<ul><li>Movshovitz-Attias, Dana and Cohen, William W. (2013) <a rel="nofollow" class="external text" href="https://www.cs.cmu.edu/~dmovshov/papers/dma_acl2013.pdf">Natural Language Models for Predicting Programming Comments</a>. In Association for Computational Linguistics (ACL), 2013.</li></ul>

<div class="mw-heading mw-heading2"><h2 id="External_links">External links</h2></div>

<ul><li><a rel="nofollow" class="external text" href="https://web.archive.org/web/20110708033309/http://dkrukovsky.blogspot.com/2005/07/how-to-write-comments.html">How to Write Comments</a> by Denis Krukovsky</li>

<li><a rel="nofollow" class="external text" href="https://web.archive.org/web/20070722211609/http://www.ptlogica.com/TwinText/resource/liveuser.pdf">Source Code Documentation as a Live User Manual</a> by PTLogica</li>

<li><a rel="nofollow" class="external text" href="https://www.oracle.com/technetwork/java/javase/tech/index-137868.html">How to Write Comments for the Javadoc Tool</a></li></ul></div><div><div class="zim-footer">

This article is issued from <a class="external text" title="Last edited on 2025-07-26" href="https://en.wikipedia.org/wiki/?title=Comment_(computer_programming)&oldid=1302652744">Wikipedia</a>. The text is available under <a class="external text" href="https://creativecommons.org/licenses/by-sa/4.0/deed.en">Creative Commons Attribution-Share Alike 4.0</a> unless otherwise noted. Additional terms may apply for the media files.

</div>

</div></div>

</div>

</main>

</div>

</body></html>